Ottimizzare Gemma per le attività di visione utilizzando Hugging Face Transformers e QLoRA

Questa guida illustra la procedura per perfezionare Gemma su un set di dati di immagini e testo personalizzato per un'attività di visione (generazione di descrizioni dei prodotti) utilizzando Transformers e TRL di Hugging Face. Scoprirai:

  • Che cos'è l'adattamento a basso ranking quantizzato (QLoRA)
  • Configura l'ambiente di sviluppo
  • Crea e prepara il set di dati per la messa a punto fine per le attività di visione
  • Ottimizzare Gemma utilizzando TRL e SFTTrainer
  • Testa l'inferenza del modello e genera descrizioni dei prodotti da immagini e testo.

Che cos'è l'adattamento a basso ranking quantizzato (QLoRA)

Questa guida illustra l'utilizzo dell'adattamento a rango basso quantizzato (QLoRA), che si è affermato come un metodo popolare per ottimizzare in modo efficiente i modelli LLM in quanto riduce i requisiti delle risorse di calcolo mantenendo un'elevata efficienza. In QloRA, il modello preaddestrato viene quantizzato a 4 bit e i pesi vengono bloccati. Vengono quindi collegati i livelli di adattatore addestrabili (LoRA) e vengono addestrati solo questi livelli. In seguito, i pesi dell'adattatore possono essere uniti al modello di base o mantenuti come adattatore separato.

Configura l'ambiente di sviluppo

Il primo passaggio consiste nell'installare le librerie Hugging Face, tra cui TRL, e i set di dati per perfezionare il modello aperto.

# Install Pytorch & other libraries
%pip install "torch>=2.4.0" tensorboard torchvision

# Install Gemma release branch from Hugging Face
%pip install "transformers>=4.51.3"

# Install Hugging Face libraries
%pip install  --upgrade \
  "datasets==3.3.2" \
  "accelerate==1.4.0" \
  "evaluate==0.4.3" \
  "bitsandbytes==0.45.3" \
  "trl==0.15.2" \
  "peft==0.14.0" \
  "pillow==11.1.0" \
  protobuf \
  sentencepiece

Prima di poter iniziare la formazione, devi assicurarti di aver accettato i termini di utilizzo di Gemma. Puoi accettare la licenza su Hugging Face facendo clic sul pulsante Accetta e accedi al repository nella pagina del modello all'indirizzo: http://huggingface.co/google/gemma-3-4b-pt (o nella pagina del modello appropriata per il modello Gemma con funzionalità di visione che stai utilizzando).

Dopo aver accettato la licenza, devi disporre di un token Hugging Face valido per accedere al modello. Se esegui il codice in Google Colab, puoi utilizzare in sicurezza il token Hugging Face utilizzando i secret di Colab; in caso contrario, puoi impostare il token direttamente nel metodo login. Assicurati che il token abbia anche l'accesso in scrittura, quando carichi il modello nell'hub durante l'addestramento.

from google.colab import userdata
from huggingface_hub import login

# Login into Hugging Face Hub
hf_token = userdata.get('HF_TOKEN') # If you are running inside a Google Colab
login(hf_token)

Crea e prepara il set di dati per la messa a punto fine

Quando perfezioni gli LLM, è importante conoscere il caso d'uso e l'attività che vuoi risolvere. In questo modo puoi creare un set di dati per perfezionare il modello. Se non hai ancora definito il tuo caso d'uso, ti consigliamo di tornare alla fase di progettazione.

Ad esempio, questa guida si concentra sul seguente caso d'uso:

  • Ottimizzazione di un modello Gemma per generare descrizioni dei prodotti concise e ottimizzate per la SEO per una piattaforma di e-commerce, personalizzata specificamente per la ricerca mobile.

Questa guida utilizza il set di dati philschmid/amazon-product-descriptions-vlm, un set di dati delle descrizioni dei prodotti di Amazon, incluse le immagini e le categorie dei prodotti.

Hugging Face TRL supporta le conversazioni multimodali. L'elemento importante è il ruolo "image", che indica alla classe di elaborazione di caricare l'immagine. La struttura deve essere la seguente:

{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}
{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}
{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}

Ora puoi utilizzare la libreria Hugging Face Datasets per caricare il set di dati e creare un modello di prompt per combinare l'immagine, il nome del prodotto e la categoria, nonché aggiungere un messaggio di sistema. Il set di dati include le immagini come oggetti Pil.Image.

from datasets import load_dataset
from PIL import Image

# System message for the assistant
system_message = "You are an expert product description writer for Amazon."

# User prompt that combines the user query and the schema
user_prompt = """Create a Short Product description based on the provided <PRODUCT> and <CATEGORY> and image.
Only return description. The description should be SEO optimized and for a better mobile search experience.

<PRODUCT>
{product}
</PRODUCT>

<CATEGORY>
{category}
</CATEGORY>
"""

# Convert dataset to OAI messages
def format_data(sample):
    return {
        "messages": [
            {
                "role": "system",
                "content": [{"type": "text", "text": system_message}],
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": user_prompt.format(
                            product=sample["Product Name"],
                            category=sample["Category"],
                        ),
                    },
                    {
                        "type": "image",
                        "image": sample["image"],
                    },
                ],
            },
            {
                "role": "assistant",
                "content": [{"type": "text", "text": sample["description"]}],
            },
        ],
    }

def process_vision_info(messages: list[dict]) -> list[Image.Image]:
    image_inputs = []
    # Iterate through each conversation
    for msg in messages:
        # Get content (ensure it's a list)
        content = msg.get("content", [])
        if not isinstance(content, list):
            content = [content]

        # Check each content element for images
        for element in content:
            if isinstance(element, dict) and (
                "image" in element or element.get("type") == "image"
            ):
                # Get the image and convert to RGB
                if "image" in element:
                    image = element["image"]
                else:
                    image = element
                image_inputs.append(image.convert("RGB"))
    return image_inputs

# Load dataset from the hub
dataset = load_dataset("philschmid/amazon-product-descriptions-vlm", split="train")

# Convert dataset to OAI messages
# need to use list comprehension to keep Pil.Image type, .mape convert image to bytes
dataset = [format_data(sample) for sample in dataset]

print(dataset[345]["messages"])

Ottimizzare Gemma utilizzando TRL e SFTTrainer

Ora è tutto pronto per perfezionare il modello. Hugging Face TRL SFTTrainer semplifica la supervisione della messa a punto di LLM aperti. SFTTrainer è una sottoclasse di Trainer della libreria transformers e supporta tutte le stesse funzionalità, tra cui logging, valutazione e checkpoint, ma aggiunge ulteriori funzionalità di qualità della vita, tra cui:

  • Formattazione del set di dati, inclusi i formati di conversazione e di istruzioni
  • Addestramento solo sui completamenti, ignorando i prompt
  • Imballaggio dei set di dati per un addestramento più efficiente
  • Supporto dell'ottimizzazione fine efficiente dei parametri (PEFT), incluso QloRA
  • Preparazione del modello e del tokenizzatore per l'ottimizzazione di conversazione (ad esempio l'aggiunta di token speciali)

Il codice seguente carica il modello e lo tokenizer Gemma da Hugging Face e inizializza la configurazione di quantizzazione.

import torch
from transformers import AutoProcessor, AutoModelForImageTextToText, BitsAndBytesConfig

# Hugging Face model id
model_id = "google/gemma-3-4b-pt" # or `google/gemma-3-12b-pt`, `google/gemma-3-27-pt`

# Check if GPU benefits from bfloat16
if torch.cuda.get_device_capability()[0] < 8:
    raise ValueError("GPU does not support bfloat16, please use a GPU that supports bfloat16.")

# Define model init arguments
model_kwargs = dict(
    attn_implementation="eager", # Use "flash_attention_2" when running on Ampere or newer GPU
    torch_dtype=torch.bfloat16, # What torch dtype to use, defaults to auto
    device_map="auto", # Let torch decide how to load the model
)

# BitsAndBytesConfig int-4 config
model_kwargs["quantization_config"] = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=model_kwargs["torch_dtype"],
    bnb_4bit_quant_storage=model_kwargs["torch_dtype"],
)

# Load model and tokenizer
model = AutoModelForImageTextToText.from_pretrained(model_id, **model_kwargs)
processor = AutoProcessor.from_pretrained("google/gemma-3-4b-it")

SFTTrainer supporta un'integrazione integrata con peft, che semplifica la messa a punto efficiente degli LLM utilizzando QLoRA. Devi solo creare un LoraConfig e fornirlo all'istruttore.

from peft import LoraConfig

peft_config = LoraConfig(
    lora_alpha=16,
    lora_dropout=0.05,
    r=16,
    bias="none",
    target_modules="all-linear",
    task_type="CAUSAL_LM",
    modules_to_save=[
        "lm_head",
        "embed_tokens",
    ],
)

Prima di poter iniziare l'addestramento, devi definire l'iperparametro da utilizzare in un SFTConfig e un collate_fn personalizzato per gestire l'elaborazione visiva. collate_fn converte i messaggi con testo e immagini in un formato comprensibile al modello.

from trl import SFTConfig

args = SFTConfig(
    output_dir="gemma-product-description",     # directory to save and repository id
    num_train_epochs=1,                         # number of training epochs
    per_device_train_batch_size=1,              # batch size per device during training
    gradient_accumulation_steps=4,              # number of steps before performing a backward/update pass
    gradient_checkpointing=True,                # use gradient checkpointing to save memory
    optim="adamw_torch_fused",                  # use fused adamw optimizer
    logging_steps=5,                            # log every 5 steps
    save_strategy="epoch",                      # save checkpoint every epoch
    learning_rate=2e-4,                         # learning rate, based on QLoRA paper
    bf16=True,                                  # use bfloat16 precision
    max_grad_norm=0.3,                          # max gradient norm based on QLoRA paper
    warmup_ratio=0.03,                          # warmup ratio based on QLoRA paper
    lr_scheduler_type="constant",               # use constant learning rate scheduler
    push_to_hub=True,                           # push model to hub
    report_to="tensorboard",                    # report metrics to tensorboard
    gradient_checkpointing_kwargs={
        "use_reentrant": False
    },  # use reentrant checkpointing
    dataset_text_field="",                      # need a dummy field for collator
    dataset_kwargs={"skip_prepare_dataset": True},  # important for collator
)
args.remove_unused_columns = False # important for collator

# Create a data collator to encode text and image pairs
def collate_fn(examples):
    texts = []
    images = []
    for example in examples:
        image_inputs = process_vision_info(example["messages"])
        text = processor.apply_chat_template(
            example["messages"], add_generation_prompt=False, tokenize=False
        )
        texts.append(text.strip())
        images.append(image_inputs)

    # Tokenize the texts and process the images
    batch = processor(text=texts, images=images, return_tensors="pt", padding=True)

    # The labels are the input_ids, and we mask the padding tokens and image tokens in the loss computation
    labels = batch["input_ids"].clone()

    # Mask image tokens
    image_token_id = [
        processor.tokenizer.convert_tokens_to_ids(
            processor.tokenizer.special_tokens_map["boi_token"]
        )
    ]
    # Mask tokens for not being used in the loss computation
    labels[labels == processor.tokenizer.pad_token_id] = -100
    labels[labels == image_token_id] = -100
    labels[labels == 262144] = -100

    batch["labels"] = labels
    return batch

Ora hai tutti i componenti di base necessari per creare il tuo SFTTrainer e iniziare l'addestramento del modello.

from trl import SFTTrainer

trainer = SFTTrainer(
    model=model,
    args=args,
    train_dataset=dataset,
    peft_config=peft_config,
    processing_class=processor,
    data_collator=collate_fn,
)

Avvia l'addestramento chiamando il metodo train().

# Start training, the model will be automatically saved to the Hub and the output directory
trainer.train()

# Save the final model again to the Hugging Face Hub
trainer.save_model()

Prima di poter testare il modello, assicurati di liberare la memoria.

# free the memory again
del model
del trainer
torch.cuda.empty_cache()

Quando utilizzi QLoRA, addestrini solo gli adattatori e non il modello completo. Ciò significa che, quando salvi il modello durante l'addestramento, vengono salvati solo i pesi dell'adattatore e non il modello completo. Se vuoi salvare il modello completo, che è più facile da utilizzare con gli stack di pubblicazione come vLLM o TGI, puoi unire i pesi dell'adattatore ai pesi del modello utilizzando il metodo merge_and_unload e poi salvare il modello con il metodo save_pretrained. Viene salvato un modello predefinito, che può essere utilizzato per l'inferenza.

from peft import PeftModel

# Load Model base model
model = AutoModelForImageTextToText.from_pretrained(model_id, low_cpu_mem_usage=True)

# Merge LoRA and base model and save
peft_model = PeftModel.from_pretrained(model, args.output_dir)
merged_model = peft_model.merge_and_unload()
merged_model.save_pretrained("merged_model", safe_serialization=True, max_shard_size="2GB")

processor = AutoProcessor.from_pretrained(args.output_dir)
processor.save_pretrained("merged_model")

Testa l'inferenza del modello e genera descrizioni dei prodotti

Al termine dell'addestramento, valuta e testa il modello. Puoi caricare diversi esempi dal set di dati di test e valutare il modello su questi esempi.

import torch

# Load Model with PEFT adapter
model = AutoModelForImageTextToText.from_pretrained(
  args.output_dir,
  device_map="auto",
  torch_dtype=torch.bfloat16,
  attn_implementation="eager",
)
processor = AutoProcessor.from_pretrained(args.output_dir)

Puoi testare l'inferenza fornendo il nome, la categoria e l'immagine di un prodotto. sample include un'action figure Marvel.

import requests
from PIL import Image

# Test sample with Product Name, Category and Image
sample = {
  "product_name": "Hasbro Marvel Avengers-Serie Marvel Assemble Titan-Held, Iron Man, 30,5 cm Actionfigur",
  "category": "Toys & Games | Toy Figures & Playsets | Action Figures",
  "image": Image.open(requests.get("https://m.media-amazon.com/images/I/81+7Up7IWyL._AC_SY300_SX300_.jpg", stream=True).raw).convert("RGB")
}

def generate_description(sample, model, processor):
    # Convert sample into messages and then apply the chat template
    messages = [
        {"role": "system", "content": [{"type": "text", "text": system_message}]},
        {"role": "user", "content": [
            {"type": "image","image": sample["image"]},
            {"type": "text", "text": user_prompt.format(product=sample["product_name"], category=sample["category"])},
        ]},
    ]
    text = processor.apply_chat_template(
        messages, tokenize=False, add_generation_prompt=True
    )
    # Process the image and text
    image_inputs = process_vision_info(messages)
    # Tokenize the text and process the images
    inputs = processor(
        text=[text],
        images=image_inputs,
        padding=True,
        return_tensors="pt",
    )
    # Move the inputs to the device
    inputs = inputs.to(model.device)

    # Generate the output
    stop_token_ids = [processor.tokenizer.eos_token_id, processor.tokenizer.convert_tokens_to_ids("<end_of_turn>")]
    generated_ids = model.generate(**inputs, max_new_tokens=256, top_p=1.0, do_sample=True, temperature=0.8, eos_token_id=stop_token_ids, disable_compile=True)
    # Trim the generation and decode the output to text
    generated_ids_trimmed = [out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)]
    output_text = processor.batch_decode(
        generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
    )
    return output_text[0]

# generate the description
description = generate_description(sample, model, processor)
print(description)

Riepilogo e passaggi successivi

Questo tutorial ha spiegato come perfezionare un modello Gemma per le attività di visione utilizzando TRL e QLoRA, in particolare per la generazione di descrizioni dei prodotti. Consulta poi la seguente documentazione: